Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@backend/app/api/deps.py`:
- Around line 52-59: Remove PII from OpenTelemetry span attributes by stopping
the direct setting of auth_context.user.email and, unless approved,
auth_context.organization.name and auth_context.project.name on spans; keep only
non-PII identifiers (span.set_attribute("user.id", ...),
span.set_attribute("tenant.org_id", ...),
span.set_attribute("tenant.project_id", ...)) or, if you need correlation,
replace the direct name/email values with a deterministic hash or masked value
before calling span.set_attribute for keys "user.email", "tenant.org_name", and
"tenant.project_name".

In `@backend/app/api/routes/llm.py`:
- Around line 162-170: The code warns when llm_call.usage is missing but still
constructs Usage(**llm_call.usage) which will raise; update the handler that
builds LLMCallResponse (the block creating LLMCallResponse with
response=llm_response, usage=Usage(**llm_call.usage), provider_raw_response=...)
to first guard llm_call.usage and either (A) return a controlled 4xx/5xx error
indicating missing usage (including job_id and project_id in the error/log) or
(B) populate a safe default Usage instance (e.g., zeros/nulls) before passing it
into LLMCallResponse; ensure the chosen approach is used consistently where
get_llm_call / LLMCallResponse and Usage are referenced so the endpoint no
longer raises when llm_call.usage is None.

In `@backend/app/core/logger.py`:
- Around line 43-68: The logging guard currently prevents reconfiguring when
configure_logging is called again, causing an old service name to persist;
update configure_logging to be service-name aware by storing the configured
service name on the root logger (e.g., add a
root_logger._kaapi_logging_service_name) and, if _kaapi_logging_configured is
True but the provided service_name (resolved_service_name) differs from
root_logger._kaapi_logging_service_name, replace or update the ServiceNameFilter
instances on existing handlers (or recreate handlers) so they use the new
resolved_service_name; ensure to update the stored _kaapi_logging_service_name
when changes are applied and keep existing use of CorrelationIdFilter and
_kaapi_logging_configured.

In `@backend/app/core/telemetry.py`:
- Around line 351-363: The loop currently checks only for key presence but may
call span.set_attribute with None; update the logic in the block that iterates
over ("gen_ai.request.temperature", "temperature") etc. to only call
span.set_attribute(attr_key, params.get(param_key)) when params.get(param_key)
is not None (i.e., guard against None values), and similarly change the tools
handling so span.set_attribute("gen_ai.request.available_tools",
json.dumps(tools)) is only executed when tools is not None and non-empty; ensure
these checks are done around the existing span.set_attribute usage so the
OpenTelemetry attributes are never set to None.

In `@backend/app/services/collections/create_collection.py`:
- Around line 279-306: The except block in create_collection.execute_job
currently logs the error, attempts provider cleanup, marks the job failed via
_mark_job_failed, and sends the failure callback (build_failure_payload +
send_callback) but then returns normally; to ensure Celery records the task as
failed, re-raise the original exception at the end of that except block (use a
bare "raise" to preserve the original traceback) immediately after sending the
callback and after _mark_job_failed completes, so the exception propagated by
span.record_exception and logger.error is not swallowed.

In `@backend/app/services/collections/delete_collection.py`:
- Around line 236-245: The exception is currently swallowed after calling
span.record_exception/ span.set_status and _mark_job_failed_and_callback, so
Celery treats the task as successful; modify the except block in the function
containing span.record_exception to re-raise the caught exception after the
failure callback: keep the existing calls to span.record_exception(err),
span.set_status(...), and _mark_job_failed_and_callback(project_id=project_id,
collection_id=collection_id, job_id=job_uuid, err=err,
callback_url=deletion_request.callback_url) and then add a plain "raise" to
re-raise the original exception so upstream task failure handling (e.g., Celery
task_failure telemetry) runs.

In `@backend/app/services/llm/jobs.py`:
- Around line 599-601: The per-LLM-call synchronous
flush_telemetry(timeout_millis=10000) in execute_llm_call is causing additive
tail latency for chain jobs; remove this unconditional 10s flush and instead
either (a) delete the call so you rely on the existing outer finally blocks and
task_postrun flush, or (b) replace the literal with a config-driven short
timeout (e.g., read TELEMETRY_PER_LLM_FLUSH_MS and default to 0/500) so the
flush is off or uses a tiny timeout by default; update execute_llm_call to
reference that config variable and ensure behavior remains backward-compatible.
- Around line 891-911: The nested except currently re-uses the outer exception
variable e, hiding the real DB/update error; modify the inner except in
execute_chain_job to catch a new variable (e.g., update_err) instead of reusing
e, and change the logger.error there to include that new variable and its
exc_info so the update_llm_chain_status failure is logged (reference
update_llm_chain_status, ChainStatus.FAILED, logger.error, and the
Session(engine) context).
- Around line 720-751: The log message in execute_job uses inconsistent
formatting for callback_url and always logs "Error if any..." at INFO level;
update the logger call that currently formats f"...callback_url
{callback_url_str}" to use an equals sign like callback_url={callback_url_str}
to match other fields, and change the post-execution logging that references
result.error so it only emits a log when result.error is truthy (e.g., if
result.error: logger.error(...)) or else demote it to debug (logger.debug(...))
— adjust the calls around the execute_llm_call invocation and the subsequent
logger usage where result and logger are referenced.

---

Outside diff comments:
In `@backend/app/api/routes/collections.py`:
- Around line 88-92: The endpoint handlers (notably create_collection and the
other handler defined around lines 156-160) lack return type annotations; add
explicit return type hints using the project's response wrapper type (the same
wrapper used elsewhere for API handlers) so signatures become e.g. def
create_collection(... ) -> ResponseWrapper[CreationResponse]: and likewise
annotate the second handler with its appropriate wrapper/response type; update
imports if needed to reference the response wrapper and the concrete response
DTO types referenced in the function bodies.

In `@backend/app/api/routes/llm.py`:
- Around line 53-55: The llm_call endpoint is missing an explicit return type;
update the function signature for llm_call to declare it returns
APIResponse[LLMJobImmediatePublic] (i.e., def llm_call(_current_user:
AuthContextDep, session: SessionDep, request: LLMCallRequest) ->
APIResponse[LLMJobImmediatePublic]:). Ensure the referenced types (APIResponse
and LLMJobImmediatePublic) are imported if not already.

In `@backend/app/services/collections/create_collection.py`:
- Around line 39-46: The function start_job is annotated to return str but
actually returns collection_job_id (a UUID); update the return type annotation
from str to UUID and ensure UUID is imported/used from uuid (or typing) so the
signature reads start_job(... ) -> UUID; verify all parameters remain fully
typed and adjust any callers or type checks expecting str if necessary.

In `@backend/app/services/collections/delete_collection.py`:
- Around line 29-35: The function start_job currently declares a return type of
str but actually returns the UUID object collection_job_id; update the signature
to return UUID (e.g., change "-> str" to "-> UUID") and ensure UUID is imported
(from uuid import UUID) so the return type matches the returned value; verify
any callers or tests expecting a str are adjusted if necessary.

---

Nitpick comments:
In `@backend/app/celery/tasks/job_execution.py`:
- Around line 19-56: The helper functions _extract_parent_context and
_run_with_otel_parent lack proper type hints for task_instance, fn, and the
return value; add typing to preserve task return types by importing TypeVar and
Callable, declare a TypeVar R for the return type, type task_instance as the
appropriate Celery Task/Any (or Task request type) and type fn as Callable[[],
R], and annotate _run_with_otel_parent to return R; also update
_extract_parent_context to return otel_context.Context (already present) and
ensure any use-sites match the new generic signature.

In `@backend/app/celery/utils.py`:
- Around line 16-23: Add an explicit type hint for the task parameter (use
celery.app.task.Task) and keep the return type as str; then wrap the call to
task.apply_async(...) in a try/except to surface broker/apply_async failures
with context: catch Exception as e and re-raise a new RuntimeError (or custom
exception) that includes the task identity (e.g., task.name) and chain the
original exception via "from e" so callers can handle or log the underlying
broker error; update any imports if needed (e.g., from celery.app.task import
Task).

In `@backend/app/core/config.py`:
- Around line 138-139: The default for OTEL_ENABLED in config.py (OTEL_ENABLED:
bool = False) conflicts with .env.example which sets OTEL_ENABLED=true; update
one to match: either change OTEL_ENABLED in config.py to True (OTEL_ENABLED:
bool = True) to reflect the example, or change the .env.example entry to
false—make the chosen source of truth consistent and keep OTEL_SERVICE_NAME
unchanged.

In `@backend/app/core/telemetry.py`:
- Line 8: Update the imports and attribute assignment to address ruff hints:
replace Iterator import from typing with importing Iterator from collections.abc
(leave TYPE_CHECKING and Any as-is) so change the import line that currently
lists "TYPE_CHECKING, Any, Iterator"; and replace the setattr call that sets
"_kaapi_db_telemetry_instrumented" on the engine (the line using setattr(engine,
"_kaapi_db_telemetry_instrumented", True)) with a direct attribute assignment
engine._kaapi_db_telemetry_instrumented = True to satisfy B010; keep the same
attribute name and effect.

In `@backend/app/services/llm/jobs.py`:
- Around line 129-173: start_chain_job currently only uses log_context and omits
creating an OpenTelemetry/Sentry span like start_job does; wrap the critical
section in tracer.start_as_current_span("llm.start_chain_job") (matching the
pattern used in start_job) around job creation + start_llm_chain_job, add the
same span.set_attribute calls and exception recording (including setting
span.status on error) so chain-start failures appear in traces, and ensure to
record the task_id and job_id on the span; locate start_chain_job and mirror the
span usage and exception handling logic from start_job to implement this.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@backend/app/services/collections/create_collection.py`:
- Around line 276-307: The exception handler and the success/failure callback
invocations must not let callback failures change the collection job outcome:
wrap the call to send_callback(creation_request.callback_url, success_payload)
and the later send_callback(..., failure_payload) each in their own try/except
that catches and logs the callback error (include context like collection_job_id
and callback URL) but does NOT re-raise; when handling the original exception in
the except block, ensure you preserve and re-raise the original exception (err)
and do not let any exception from the failure callback mask it—i.e., call
send_callback inside a try/except that logs warnings and continues, then call
_mark_job_failed(...) and finally re-raise the original err; also apply the same
non-fatal try/except around provider.delete(result) cleanup so cleanup/callback
failures don't overwrite job failure handling.

---

Outside diff comments:
In `@backend/app/services/collections/create_collection.py`:
- Around line 39-76: The function start_job has a return type annotation of ->
str but actually returns collection_job_id (a UUID); update the signature to
return UUID (use the same UUID type used for the collection_job_id parameter) so
the annotation matches the implementation, i.e., change -> str to -> UUID in
start_job and ensure UUID is imported where needed; alternatively, if callers
expect a string, convert the returned value to str(collection_job_id) before
returning—make this consistent with usages of start_job in the codebase (refer
to start_job, collection_job_id, and start_create_collection_job).

In `@backend/app/services/collections/delete_collection.py`:
- Around line 29-65: The function start_job currently annotates its return as
str but returns collection_job_id (a UUID); fix by making the annotation match
the implementation or vice versa: either change the return type annotation on
start_job to -> UUID (and ensure UUID is imported) if callers expect a UUID, or
return str(collection_job_id) and update any callers/types accordingly;
reference the start_job function, collection_job_id variable, and the return
statement to locate the change.
- Around line 143-149: The callback sending and failure-marking logic (calls to
send_callback and build_failure_payload and the helper
_mark_job_failed_and_callback) must be isolated so errors in sending callbacks
do not change the deletion job state or swallow the original exception: wrap
send_callback and the code path that builds/sends failure callbacks in their own
try/except blocks, log any callback/send errors but do not call
_mark_job_failed_and_callback from inside the same broad exception path that
handles the deletion result, and ensure that any exception raised during
deletion is re-raised after attempts to notify; likewise protect
_mark_job_failed_and_callback itself with its own try/except so its failures are
logged and do not prevent the original exception from being re-raised. Ensure
you reference and modify the code around send_callback, build_failure_payload,
and _mark_job_failed_and_callback to implement these isolated try/excepts and
re-raise the original exception at the end of the outer exception handler.

In `@backend/app/services/llm/jobs.py`:
- Around line 494-583: The provider setup and execution error paths
(get_llm_provider ValueError, inner try ValueError, and any exceptions that
bubble to the outer except) return before calling record_llm_call_finished,
undercounting errors; update the failure exits to always call
record_llm_call_finished(provider=provider_name, model=model_name,
operation="chat", duration_ms=(time.perf_counter()-provider_started_at)*1000,
error=True, organization_id=organization_id, project_id=project_id) before
returning and ensure provider_started_at, provider_name and model_name are
initialized for the outer except path (e.g. set defaults before provider lookup)
so the outer exception handler can emit the same metric and then return the
BlockResult (also keep existing ai_span.set_status calls where applicable).
- Around line 182-198: The span currently records the full callback URL and the
code sends callbacks before updating DB state; change both success and failure
flows to update the job status first via JobCrud.update(JobUpdate(...)) and then
attempt a best-effort send_callback inside a try/except so callback failures do
not prevent DB updates, and remove the raw URL from the span (use an obfuscated
value or just record the host/domain or a hash under
tracer.start_as_current_span("llm.send_callback") instead of the full
callback_url) while recording any send error in the span or logs; apply this
pattern to the failure branch shown (send_callback, cb_span.set_attribute) and
the analogous success branch so send_callback is post-update and wrapped in
exception handling.

---

Duplicate comments:
In `@backend/app/core/telemetry.py`:
- Around line 356-368: The telemetry code currently sets OpenTelemetry
attributes even when values are None or empty; update the loop over
("gen_ai.request.temperature", ...) in the function/method using span so that
you read value = params.get(param_key) and only call
span.set_attribute(attr_key, value) when value is not None (and for
numeric/boolean semantics consider explicitly checking value is not None), and
change the tools handling (variable tools = params.get("tools")) to only set
"gen_ai.request.available_tools" when tools is truthy/non-empty (e.g., if tools:
span.set_attribute(..., json.dumps(tools))) to avoid recording undefined or
empty attributes.

---

Nitpick comments:
In `@backend/app/core/telemetry.py`:
- Around line 514-559: Update the SQLAlchemy event listener functions to add
parameter type hints (use typing.Any for dynamic SQLAlchemy args) and explicit
return type None: _before_cursor_execute(conn: Any, cursor: Any, statement: Any,
parameters: Any, context: Any, executemany: Any) -> None,
_after_cursor_execute(conn: Any, cursor: Any, statement: Any, parameters: Any,
context: Any, executemany: Any) -> None, _handle_error(exception_context: Any)
-> None, _on_checkout(dbapi_connection: Any, connection_record: Any,
connection_proxy: Any) -> None, and _on_checkin(dbapi_connection: Any,
connection_record: Any) -> None; also add "from typing import Any" at the top of
the module if not present.
- Line 563: Replace the setattr call that sets the instrumentation marker with a
direct attribute assignment on the engine object: change setattr(engine,
"_kaapi_db_telemetry_instrumented", True) to
engine._kaapi_db_telemetry_instrumented = True; if type checkers complain about
engine being typed as object, retain the existing attr-defined suppression
comment so static checks remain satisfied; ensure you update the code around the
instrumentation logic that references engine and the
"_kaapi_db_telemetry_instrumented" attribute.

In `@backend/app/services/llm/jobs.py`:
- Around line 55-63: The helper _execute_provider_call has an untyped callable
and a bare dict; update its signature to type func as a Callable that returns
the same tuple[Any, Any] (e.g. Callable[..., tuple[Any, Any]] or a more specific
Callable[[Any, QueryParams, dict[str, Any] | None, str | None], tuple[Any,
Any]]), and change credentials from bare dict | None to dict[str, Any] | None
(or Mapping[str, Any] | None) and add the necessary imports (Callable, Mapping)
from typing. Ensure the updated type hints are used for func, credentials, and
any other parameters so the function signature and return annotation are fully
typed.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@backend/app/api/routes/collections.py`:
- Around line 107-132: The job record uses deduplicated IDs (unique_documents)
but create_service.start_job is still passed the original request, so the worker
may process duplicates; update the call to create_service.start_job to pass a
request object whose documents field is the deduplicated list (use
unique_documents or set request.documents = unique_documents before the call, or
create a shallow copy of request with documents=[str(doc_id) for doc_id in
unique_documents]) so the worker receives the same deduplicated document list
used to create the CollectionJob (references: unique_documents,
CollectionJobCreate, create_service.start_job).

In `@backend/app/tests/services/collections/test_delete_collection.py`:
- Around line 373-376: The test functions (e.g.,
test_execute_job_local_delete_failure_after_remote_success_marks_failed) are
missing a type annotation for the db fixture; add a parameter type hint db:
Session and ensure you import Session (e.g., from sqlalchemy.orm import Session)
at the top of the test module, and apply the same change to the other new
test(s) referenced (around lines 441-444) so all fixture parameters are properly
typed.

---

Nitpick comments:
In `@backend/app/celery/celery_app.py`:
- Around line 80-123: The task_postrun flush handler currently lives nested
inside initialize_worker_process and uses an untyped **_ parameter; move the
`@task_postrun.connect`(weak=False) subscriber out to module scope (co-locate it
with log_pool_status_post) so task-flush wiring is visible and not coupled to
Sentry/OTel init, and change the handler signature to def
_flush_otel_after_task(**_: object) -> None to add the missing type hint; the
handler should simply call flush_telemetry() and retain weak=False on the
decorator.